﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
   <head>
      <meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
      <title>Startup Template (ASP.NET Core with Angular)</title>
      <link type="text/css" rel="stylesheet" href="../bootstrap.min.css" />
   </head>
   <body>
      <div class="document-contents">
         <h3>Introduction</h3>
         <p>The easiest way of starting a new project using ABP with <strong>ASP.NET Core</strong> with 
		 <strong>Angular</strong> is to create a 
            template on <a href="/Templates">templates page</a>. Remember to check "<strong>Include 
            module zero</strong>".
         After creating and downloading your project, follow below steps to run your application.</p>
         <h3>ASP.NET Core Application</h3>
         <ul>
            <li>Open your solution on <strong>Visual Studio 2017+</strong> and
			<strong>build</strong> the solution.</li>
            <li>Select the '<strong>Web.Host</strong>' project as <strong>startup project</strong>.</li>
            <li>Open <strong>Package Manager Console</strong> and run <strong>
			Update-Database</strong> command to create your database (ensure 
			that Default project is selected as <strong>.EntityFrameworkCore</strong> 
			in the Package Manager Console window).</li>
            <li>Run the application. It will show <strong>swagger-ui</strong> if 
			it is successfull:</li>
         </ul>
          <p>
		  <img class="img-thumbnail" alt="Swagger UI" src="../images/swagger-ui-module-zero-core-template.png" /></p>
         <p>In this template, <strong>multi-tenancy is enabled by default</strong>. You 
            can disable it in Core project's module class if you don't need.
         </p>
			<div class="bs-callout bs-callout-warning">
				<p>If you have problems with running the application, please try 
				close and open your Visual Studio again. It sometimes fail on 
				first package restore.</p>
			</div>

         <h3>Angular Application</h3>
         <h4>Prerequirements</h4>
		 <p>
			 Angular application needs to following tools be installed:
		 </p>
		 <ul>
			<li><a href="https://nodejs.org/en/download/" target="_blank">nodejs</a> 6.9+ with npm 3.10+</li>
			<li>Typescript 2.0+</li>
		</ul>
		  <p>We used <a href="https://cli.angular.io/" target="_blank">
		  angular-cli</a> to develop the Angular application.</p>
		<h4>Restore Packages</h4>
		<p>Open a command prompt, navigate to <strong>angular</strong> folder which contains *.sln file and run the following command to 
		<strong>restore npm packages</strong>:</p>
		<pre class="js">npm install</pre>
		<p>Notice that npm install may show some warn messages, which is not related to our solution and generally it's not a problem. 
		The solution can also configured to work with
		<a href="https://yarnpkg.com/" target="_blank"><strong>yarn</strong></a> 
		and we suggest to use it if available on your computer.</p>
		<h4>Run The Application</h4>
		<p>In your opened command prompt, run the following command:</p>
		<pre class="js">npm start</pre>
		<p>Once the application compiled, you can browse <a href="http://localhost:4200">http://localhost:4200</a> in your browser. 
		Be sure that Web.Host application is running at the same time. When you 
		open the application, you will see the <strong>login page</strong>:</p>
		  <p>
		  <img class="img-thumbnail" alt="Login Page" src="../images/module-zero-core-template-ui-login.png" /></p>
		  <p>Angular client app has also <strong>HMR</strong> (Hot Module Replacement) enabled. You can use the 
		following command (instead of npm start) to enable HMR on development time:</p>
		<pre class="js">npm run hmr</pre>
		  <h4>Login</h4>
		<p>Now you can login the application using default credentials. User name is '<strong>admin</strong>' and password is '<strong>123qwe</strong>' as default. 
		If you want to login as a tenant, first switch to that tenant in login 
		page. There is a tenant named &quot;Default&quot; by default. Once you 
		login successfully, you will see a dashboard:</p>
		  <p>
		  <img class="img-thumbnail" alt="Dashboard" src="../images/module-zero-core-template-ui-home.png" /></p>
		  <p>This dashboard is just for demonstration and to be a base for your 
		  actual dashboard.</p>

      <h4>Deployment of Angular Application</h4>

	  <p>We used <strong>angular-cli</strong> tooling to build Angular solution. 
	  You can use <strong>ng build</strong> command to publish your project. It 
	  publishes to <strong>dist</strong> folder by default. Then you can host this folder on 
	  IIS or any web server you like.</p>
		  <h3>Solution Details &amp; Other Features</h3>

         <h4>Token Based Authentication</h4>
         <p>If you want to consume APIs/application services from a mobile application, you can use token based 
            authentication mechanism just like we do it for Angular client. Startup template includes JwtBearer token authentication 
            infrastructure.
         </p>
         <p>Here, <strong>Postman</strong> (chrome extension) will be used to demonstrate 
            requests and responses.
         </p>
         <h5>Authentication</h5>
         <p>Just send a <strong>POST</strong> request to <strong>
		 http://localhost:21021/api/TokenAuth/Authenticate</strong> with <strong>Context-Type="application/json"</strong> header as shown below:</p>
         <p>
		 <img class="img-thumbnail" alt="Swagger UI auth" src="../images/swagger-ui-angular-auth.png" /></p>
         <p>We sent values <strong>usernameOrEmailAddress
            </strong>and <strong>password</strong>. As seen above, result property of returning JSON contains the token and expire time (which is 24 hours by default and can be configured). We can save it and use for next requests.</p>

			<div class="bs-callout bs-callout-warning">
				<p><strong>About Multi Tenancy<br />
				</strong>API will work as host users by default. You can send
				<strong>Abp.TenantId</strong> header value to work with a 
				specified tenant. It's an integer value and 1 for default tenant 
				by default.</p>
			</div>

         <h5>Use API</h5>
         <p>After authenticate and get the <strong>token</strong>, we can use it to call any <strong>authorized</strong> 
            action. All <strong>application services </strong>are available to be used remotely. For 
            example,  we can use the <strong>User service</strong> to get a <strong>list of users</strong>:
         </p>
         <p>
            <img class="img-thumbnail" alt="Using API" src="../images/swagger-ui-angular-api-v2.png"/></p>
         <p>Just made a <strong>GET</strong> request to <strong>
		 http://localhost:21021/api/services/app/user/getAll</strong> with <strong>
            Content-Type="application/json"</strong> and <strong>Authorization="Bearer <em>
            your-</em></strong><em><strong>auth-token</strong>
            </em>
            <strong>"</strong>.
         All functionality available on UI is also available as API.</p>
         <h4>Migrator Console Application</h4>
         <p>Startup template includes a tool, Migrator.exe, to easily migrate your databases. 
            You can run this application to create/migrate host and tenant databases.
         </p>
         <p>
            <img class="img-thumbnail" alt="Database Migrator" src="../images/database-migrator.png" />
         </p>
         <p>This application gets host connection string from it's <strong>own 
		 appsettings.json 
            file</strong>. It will be same in the appsettings.json in the 
		 .Web.Host project at the beggining. Be sure that 
            the connection string in config file is the database you want. After getting
            <strong class="auto-style2">host </strong><strong>connection sring</strong>, it 
            first creates the host database or apply migrations if it does already exists. 
            Then it gets connection strings of tenant databases and runs migrations for 
            those databases. It skips a tenant if it has not a dedicated database or it's 
            database is already migrated for another tenant (for shared databases between 
            multiple tenants).
         </p>
         <p>You can use this tool on development or on product environment to 
            migrate databases on deployment, instead of EntityFramework's own 
            tooling (which requires some configuration and can work for 
            single database/tenant in one run).
         </p>
         <h4>Unit Testing</h4>
         <p>Startup template includes test infrastructure setup and a few tests under 
            the .Test project. You can check them and write similar tests easily. 
            Actually, they are integration tests rather than unit tests since they tests 
            your code with all ASP.NET Boilerplate infrastructure (including validation, 
            authorization, unit of work...).
         </p>
		  <h3>Source Code</h3>
		  <p>This project template is developed as open source and free under 
		  Github:
		  <a href="https://github.com/aspnetboilerplate/module-zero-core-template">
		  https://github.com/aspnetboilerplate/module-zero-core-template</a></p>

      </div>
   </body>
</html>